home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_emacs-lisp-intro.idb / usr / freeware / info / emacs-lisp-intro.info-5.z / emacs-lisp-intro.info-5
Text File  |  2002-07-08  |  50KB  |  1,260 lines

  1. This is emacs-lisp-intro.info, produced by makeinfo version 4.0b from
  2. emacs-lisp-intro.texi.
  3.  
  4. INFO-DIR-SECTION Emacs
  5. START-INFO-DIR-ENTRY
  6. * Emacs Lisp Intro: (eintr).
  7.               A simple introduction to Emacs Lisp programming.
  8. END-INFO-DIR-ENTRY
  9.  
  10.    This is an introduction to `Programming in Emacs Lisp', for people
  11. who are not programmers.
  12.  
  13.    Edition 2.04, 2001 Dec 17
  14.  
  15.    Copyright (C) 1990, '91, '92, '93, '94, '95, '97, 2001 Free Software
  16. Foundation, Inc.
  17.  
  18.    Permission is granted to copy, distribute and/or modify this document
  19. under the terms of the GNU Free Documentation License, Version 1.1 or
  20. any later version published by the Free Software Foundation; with the
  21. Invariant Section being the Preface, with the Front-Cover Texts being
  22. no Front-Cover Texts, and with the Back-Cover Texts being no Back-Cover
  23. Texts.  A copy of the license is included in the section entitled "GNU
  24. Free Documentation License".
  25.  
  26. 
  27. File: emacs-lisp-intro.info,  Node: if & or,  Next: Insert or,  Prev: insert-buffer body,  Up: insert-buffer
  28.  
  29. `insert-buffer' With an `if' Instead of an `or'
  30. -----------------------------------------------
  31.  
  32.    The job to be done is to make sure the value of `buffer' is a buffer
  33. itself and not the name of a buffer.  If the value is the name, then
  34. the buffer itself must be got.
  35.  
  36.    You can imagine yourself at a conference where an usher is wandering
  37. around holding a list with your name on it and looking for you: the
  38. usher is "bound" to your name, not to you; but when the usher finds you
  39. and takes your arm, the usher becomes "bound" to you.
  40.  
  41.    In Lisp, you might describe this situation like this:
  42.  
  43.      (if (not (holding-on-to-guest))
  44.          (find-and-take-arm-of-guest))
  45.  
  46.    We want to do the same thing with a buffer--if we do not have the
  47. buffer itself, we want to get it.
  48.  
  49.    Using a predicate called `bufferp' that tells us whether we have a
  50. buffer (rather than its name), we can write the code like this:
  51.  
  52.      (if (not (bufferp buffer))              ; if-part
  53.          (setq buffer (get-buffer buffer)))  ; then-part
  54.  
  55. Here, the true-or-false-test of the `if' expression is
  56. `(not (bufferp buffer))'; and the then-part is the expression
  57. `(setq buffer (get-buffer buffer))'.
  58.  
  59.    In the test, the function `bufferp' returns true if its argument is
  60. a buffer--but false if its argument is the name of the buffer.  (The
  61. last character of the function name `bufferp' is the character `p'; as
  62. we saw earlier, such use of `p' is a convention that indicates that the
  63. function is a predicate, which is a term that means that the function
  64. will determine whether some property is true or false.  *Note Using the
  65. Wrong Type Object as an Argument: Wrong Type of Argument.)
  66.  
  67.    The function `not' precedes the expression `(bufferp buffer)', so
  68. the true-or-false-test looks like this:
  69.  
  70.      (not (bufferp buffer))
  71.  
  72. `not' is a function that returns true if its argument is false and
  73. false if its argument is true.  So if `(bufferp buffer)' returns true,
  74. the `not' expression returns false and vice-versa: what is "not true"
  75. is false and what is "not false" is true.
  76.  
  77.    Using this test, the `if' expression works as follows: when the
  78. value of the variable `buffer' is actually a buffer rather then its
  79. name, the true-or-false-test returns false and the `if' expression does
  80. not evaluate the then-part.  This is fine, since we do not need to do
  81. anything to the variable `buffer' if it really is a buffer.
  82.  
  83.    On the other hand, when the value of `buffer' is not a buffer
  84. itself, but the name of a buffer, the true-or-false-test returns true
  85. and the then-part of the expression is evaluated.  In this case, the
  86. then-part is `(setq buffer (get-buffer buffer))'.  This expression uses
  87. the `get-buffer' function to return an actual buffer itself, given its
  88. name.  The `setq' then sets the variable `buffer' to the value of the
  89. buffer itself, replacing its previous value (which was the name of the
  90. buffer).
  91.  
  92. 
  93. File: emacs-lisp-intro.info,  Node: Insert or,  Next: Insert let,  Prev: if & or,  Up: insert-buffer
  94.  
  95. The `or' in the Body
  96. --------------------
  97.  
  98.    The purpose of the `or' expression in the `insert-buffer' function
  99. is to ensure that the argument `buffer' is bound to a buffer and not
  100. just to the name of a buffer.  The previous section shows how the job
  101. could have been done using an `if' expression.  However, the
  102. `insert-buffer' function actually uses `or'.  To understand this, it is
  103. necessary to understand how `or' works.
  104.  
  105.    An `or' function can have any number of arguments.  It evaluates
  106. each argument in turn and returns the value of the first of its
  107. arguments that is not `nil'.  Also, and this is a crucial feature of
  108. `or', it does not evaluate any subsequent arguments after returning the
  109. first non-`nil' value.
  110.  
  111.    The `or' expression looks like this:
  112.  
  113.      (or (bufferp buffer)
  114.          (setq buffer (get-buffer buffer)))
  115.  
  116. The first argument to `or' is the expression `(bufferp buffer)'.  This
  117. expression returns true (a non-`nil' value) if the buffer is actually a
  118. buffer, and not just the name of a buffer.  In the `or' expression, if
  119. this is the case, the `or' expression returns this true value and does
  120. not evaluate the next expression--and this is fine with us, since we do
  121. not want to do anything to the value of `buffer' if it really is a
  122. buffer.
  123.  
  124.    On the other hand, if the value of `(bufferp buffer)' is `nil',
  125. which it will be if the value of `buffer' is the name of a buffer, the
  126. Lisp interpreter evaluates the next element of the `or' expression.
  127. This is the expression `(setq buffer (get-buffer buffer))'.  This
  128. expression returns a non-`nil' value, which is the value to which it
  129. sets the variable `buffer'--and this value is a buffer itself, not the
  130. name of a buffer.
  131.  
  132.    The result of all this is that the symbol `buffer' is always bound
  133. to a buffer itself rather than to the name of a buffer.  All this is
  134. necessary because the `set-buffer' function in a following line only
  135. works with a buffer itself, not with the name to a buffer.
  136.  
  137.    Incidentally, using `or', the situation with the usher would be
  138. written like this:
  139.  
  140.      (or (holding-on-to-guest) (find-and-take-arm-of-guest))
  141.  
  142. 
  143. File: emacs-lisp-intro.info,  Node: Insert let,  Prev: Insert or,  Up: insert-buffer
  144.  
  145. The `let' Expression in `insert-buffer'
  146. ---------------------------------------
  147.  
  148.    After ensuring that the variable `buffer' refers to a buffer itself
  149. and not just to the name of a buffer, the `insert-buffer function'
  150. continues with a `let' expression.  This specifies three local
  151. variables, `start', `end', and `newmark' and binds them to the initial
  152. value `nil'.  These variables are used inside the remainder of the
  153. `let' and temporarily hide any other occurrence of variables of the
  154. same name in Emacs until the end of the `let'.
  155.  
  156.    The body of the `let' contains two `save-excursion' expressions.
  157. First, we will look at the inner `save-excursion' expression in detail.
  158. The expression looks like this:
  159.  
  160.      (save-excursion
  161.        (set-buffer buffer)
  162.        (setq start (point-min) end (point-max)))
  163.  
  164. The expression `(set-buffer buffer)' changes Emacs' attention from the
  165. current buffer to the one from which the text will copied.  In that
  166. buffer, the variables `start' and `end' are set to the beginning and
  167. end of the buffer, using the commands `point-min' and `point-max'.
  168. Note that we have here an illustration of how `setq' is able to set two
  169. variables in the same expression.  The first argument of `setq' is set
  170. to the value of its second, and its third argument is set to the value
  171. of its fourth.
  172.  
  173.    After the body of the inner `save-excursion' is evaluated, the
  174. `save-excursion' restores the original buffer, but `start' and `end'
  175. remain set to the values of the beginning and end of the buffer from
  176. which the text will be copied.
  177.  
  178.    The outer `save-excursion' expression looks like this:
  179.  
  180.      (save-excursion
  181.        (INNER-`save-excursion'-EXPRESSION
  182.           (GO-TO-NEW-BUFFER-AND-SET-`start'-AND-`end')
  183.        (insert-buffer-substring buffer start end)
  184.        (setq newmark (point)))
  185.  
  186. The `insert-buffer-substring' function copies the text _into_ the
  187. current buffer _from_ the region indicated by `start' and `end' in
  188. `buffer'.  Since the whole of the second buffer lies between `start'
  189. and `end', the whole of the second buffer is copied into the buffer you
  190. are editing.  Next, the value of point, which will be at the end of the
  191. inserted text, is recorded in the variable `newmark'.
  192.  
  193.    After the body of the outer `save-excursion' is evaluated, point and
  194. mark are relocated to their original places.
  195.  
  196.    However, it is convenient to locate a mark at the end of the newly
  197. inserted text and locate point at its beginning.  The `newmark'
  198. variable records the end of the inserted text.  In the last line of the
  199. `let' expression, the `(push-mark newmark)' expression function sets a
  200. mark to this location.  (The previous location of the mark is still
  201. accessible; it is recorded on the mark ring and you can go back to it
  202. with `C-u C-<SPC>'.)  Meanwhile, point is located at the beginning of
  203. the inserted text, which is where it was before you called the insert
  204. function.
  205.  
  206.    The whole `let' expression looks like this:
  207.  
  208.      (let (start end newmark)
  209.        (save-excursion
  210.          (save-excursion
  211.            (set-buffer buffer)
  212.            (setq start (point-min) end (point-max)))
  213.          (insert-buffer-substring buffer start end)
  214.          (setq newmark (point)))
  215.        (push-mark newmark))
  216.  
  217.    Like the `append-to-buffer' function, the `insert-buffer' function
  218. uses `let', `save-excursion', and `set-buffer'.  In addition, the
  219. function illustrates one way to use `or'.  All these functions are
  220. building blocks that we will find and use again and again.
  221.  
  222. 
  223. File: emacs-lisp-intro.info,  Node: beginning-of-buffer,  Next: Second Buffer Related Review,  Prev: insert-buffer,  Up: More Complex
  224.  
  225. Complete Definition of `beginning-of-buffer'
  226. ============================================
  227.  
  228.    The basic structure of the `beginning-of-buffer' function has
  229. already been discussed.  (*Note A Simplified `beginning-of-buffer'
  230. Definition: simplified-beginning-of-buffer.)  This section describes
  231. the complex part of the definition.
  232.  
  233.    As previously described, when invoked without an argument,
  234. `beginning-of-buffer' moves the cursor to the beginning of the buffer,
  235. leaving the mark at the previous position.  However, when the command
  236. is invoked with a number between one and ten, the function considers
  237. that number to be a fraction of the length of the buffer, measured in
  238. tenths, and Emacs moves the cursor that fraction of the way from the
  239. beginning of the buffer.  Thus, you can either call this function with
  240. the key command `M-<', which will move the cursor to the beginning of
  241. the buffer, or with a key command such as `C-u 7 M-<' which will move
  242. the cursor to a point 70% of the way through the buffer.  If a number
  243. bigger than ten is used for the argument, it moves to the end of the
  244. buffer.
  245.  
  246.    The `beginning-of-buffer' function can be called with or without an
  247. argument.  The use of the argument is optional.
  248.  
  249. * Menu:
  250.  
  251. * Optional Arguments::
  252. * beginning-of-buffer opt arg::  Example with optional argument.
  253. * beginning-of-buffer complete::
  254.  
  255. 
  256. File: emacs-lisp-intro.info,  Node: Optional Arguments,  Next: beginning-of-buffer opt arg,  Prev: beginning-of-buffer,  Up: beginning-of-buffer
  257.  
  258. Optional Arguments
  259. ------------------
  260.  
  261.    Unless told otherwise, Lisp expects that a function with an argument
  262. in its function definition will be called with a value for that
  263. argument.  If that does not happen, you get an error and a message that
  264. says `Wrong number of arguments'.
  265.  
  266.    However, optional arguments are a feature of Lisp: a "keyword" may
  267. be used to tell the Lisp interpreter that an argument is optional.  The
  268. keyword is `&optional'.  (The `&' in front of `optional' is part of the
  269. keyword.)  In a function definition, if an argument follows the keyword
  270. `&optional', a value does not need to be passed to that argument when
  271. the function is called.
  272.  
  273.    The first line of the function definition of `beginning-of-buffer'
  274. therefore looks like this:
  275.  
  276.      (defun beginning-of-buffer (&optional arg)
  277.  
  278.    In outline, the whole function looks like this:
  279.  
  280.      (defun beginning-of-buffer (&optional arg)
  281.        "DOCUMENTATION..."
  282.        (interactive "P")
  283.        (push-mark)
  284.        (goto-char
  285.          (IF-THERE-IS-AN-ARGUMENT
  286.              FIGURE-OUT-WHERE-TO-GO
  287.            ELSE-GO-TO
  288.            (point-min))))
  289.  
  290.    The function is similar to the `simplified-beginning-of-buffer'
  291. function except that the `interactive' expression has `"P"' as an
  292. argument and the `goto-char' function is followed by an if-then-else
  293. expression that figures out where to put the cursor if there is an
  294. argument.
  295.  
  296.    The `"P"' in the `interactive' expression tells Emacs to pass a
  297. prefix argument, if there is one, to the function.  A prefix argument
  298. is made by typing the <META> key followed by a number, or by typing
  299. `C-u' and then a number (if you don't type a number, `C-u' defaults to
  300. 4).
  301.  
  302.    The true-or-false-test of the `if' expression is simple: it is
  303. simply the argument `arg'.  If `arg' has a value that is not `nil',
  304. which will be the case if `beginning-of-buffer' is called with an
  305. argument, then this true-or-false-test will return true and the
  306. then-part of the `if' expression will be evaluated.  On the other hand,
  307. if `beginning-of-buffer' is not called with an argument, the value of
  308. `arg' will be `nil' and the else-part of the `if' expression will be
  309. evaluated.  The else-part is simply `point-min', and when this is the
  310. outcome, the whole `goto-char' expression is `(goto-char (point-min))',
  311. which is how we saw the `beginning-of-buffer' function in its simplified
  312. form.
  313.  
  314. 
  315. File: emacs-lisp-intro.info,  Node: beginning-of-buffer opt arg,  Next: beginning-of-buffer complete,  Prev: Optional Arguments,  Up: beginning-of-buffer
  316.  
  317. `beginning-of-buffer' with an Argument
  318. --------------------------------------
  319.  
  320.    When `beginning-of-buffer' is called with an argument, an expression
  321. is evaluated which calculates what value to pass to `goto-char'.  This
  322. expression is rather complicated at first sight.  It includes an inner
  323. `if' expression and much arithmetic.  It looks like this:
  324.  
  325.      (if (> (buffer-size) 10000)
  326.          ;; Avoid overflow for large buffer sizes!
  327.          (* (prefix-numeric-value arg) (/ (buffer-size) 10))
  328.        (/
  329.         (+ 10
  330.            (*
  331.             (buffer-size) (prefix-numeric-value arg))) 10))
  332.  
  333. * Menu:
  334.  
  335. * Disentangle beginning-of-buffer::
  336. * Large buffer case::
  337. * Small buffer case::
  338.  
  339. 
  340. File: emacs-lisp-intro.info,  Node: Disentangle beginning-of-buffer,  Next: Large buffer case,  Prev: beginning-of-buffer opt arg,  Up: beginning-of-buffer opt arg
  341.  
  342. Disentangle `beginning-of-buffer'
  343. .................................
  344.  
  345.    Like other complex-looking expressions, the conditional expression
  346. within `beginning-of-buffer' can be disentangled by looking at it as
  347. parts of a template, in this case, the template for an if-then-else
  348. expression.  In skeletal form, the expression looks like this:
  349.  
  350.      (if (BUFFER-IS-LARGE
  351.          DIVIDE-BUFFER-SIZE-BY-10-AND-MULTIPLY-BY-ARG
  352.        ELSE-USE-ALTERNATE-CALCULATION
  353.  
  354.    The true-or-false-test of this inner `if' expression checks the size
  355. of the buffer.  The reason for this is that the old Version 18 Emacs
  356. used numbers that are no bigger than eight million or so and in the
  357. computation that followed, the programmer feared that Emacs might try
  358. to use over-large numbers if the buffer were large.  The term
  359. `overflow', mentioned in the comment, means numbers that are over
  360. large.  Version 21 Emacs uses larger numbers, but this code has not
  361. been touched, if only because people now look at buffers that are far,
  362. far larger than ever before.
  363.  
  364.    There are two cases:  if the buffer is large and if it is not.
  365.  
  366. 
  367. File: emacs-lisp-intro.info,  Node: Large buffer case,  Next: Small buffer case,  Prev: Disentangle beginning-of-buffer,  Up: beginning-of-buffer opt arg
  368.  
  369. What happens in a large buffer
  370. ..............................
  371.  
  372.    In `beginning-of-buffer', the inner `if' expression tests whether
  373. the size of the buffer is greater than 10,000 characters.  To do this,
  374. it uses the `>' function and the `buffer-size' function.
  375.  
  376.    The line looks like this:
  377.  
  378.      (if (> (buffer-size) 10000)
  379.  
  380. When the buffer is large, the then-part of the `if' expression is
  381. evaluated.  It reads like this (after formatting for easy reading):
  382.  
  383.      (*
  384.        (prefix-numeric-value arg)
  385.        (/ (buffer-size) 10))
  386.  
  387. This expression is a multiplication, with two arguments to the function
  388. `*'.
  389.  
  390.    The first argument is `(prefix-numeric-value arg)'.  When `"P"' is
  391. used as the argument for `interactive', the value passed to the
  392. function as its argument is passed a "raw prefix argument", and not a
  393. number.  (It is a number in a list.)  To perform the arithmetic, a
  394. conversion is necessary, and `prefix-numeric-value' does the job.
  395.  
  396.    The second argument is `(/ (buffer-size) 10)'.  This expression
  397. divides the numeric value of the buffer by ten.  This produces a number
  398. that tells how many characters make up one tenth of the buffer size.
  399. (In Lisp, `/' is used for division, just as `*' is used for
  400. multiplication.)
  401.  
  402.    In the multiplication expression as a whole, this amount is
  403. multiplied by the value of the prefix argument--the multiplication
  404. looks like this:
  405.  
  406.      (* NUMERIC-VALUE-OF-PREFIX-ARG
  407.         NUMBER-OF-CHARACTERS-IN-ONE-TENTH-OF-THE-BUFFER)
  408.  
  409. If, for example, the prefix argument is `7', the one-tenth value will
  410. be multiplied by 7 to give a position 70% of the way through the buffer.
  411.  
  412.    The result of all this is that if the buffer is large, the
  413. `goto-char' expression reads like this:
  414.  
  415.      (goto-char (* (prefix-numeric-value arg)
  416.                    (/ (buffer-size) 10)))
  417.  
  418.    This puts the cursor where we want it.
  419.  
  420. 
  421. File: emacs-lisp-intro.info,  Node: Small buffer case,  Prev: Large buffer case,  Up: beginning-of-buffer opt arg
  422.  
  423. What happens in a small buffer
  424. ..............................
  425.  
  426.    If the buffer contains fewer than 10,000 characters, a slightly
  427. different computation is performed.  You might think this is not
  428. necessary, since the first computation could do the job.  However, in a
  429. small buffer, the first method may not put the cursor on exactly the
  430. desired line; the second method does a better job.
  431.  
  432.    The code looks like this:
  433.  
  434.      (/ (+ 10 (* (buffer-size) (prefix-numeric-value arg))) 10))
  435.  
  436. This is code in which you figure out what happens by discovering how the
  437. functions are embedded in parentheses.  It is easier to read if you
  438. reformat it with each expression indented more deeply than its
  439. enclosing expression:
  440.  
  441.        (/
  442.         (+ 10
  443.            (*
  444.             (buffer-size)
  445.             (prefix-numeric-value arg)))
  446.         10))
  447.  
  448. Looking at parentheses, we see that the innermost operation is
  449. `(prefix-numeric-value arg)', which converts the raw argument to a
  450. number.  This number is multiplied by the buffer size in the following
  451. expression:
  452.  
  453.      (* (buffer-size) (prefix-numeric-value arg)
  454.  
  455. This multiplication creates a number that may be larger than the size of
  456. the buffer--seven times larger if the argument is 7, for example.  Ten
  457. is then added to this number and finally the large number is divided by
  458. ten to provide a value that is one character larger than the percentage
  459. position in the buffer.
  460.  
  461.    The number that results from all this is passed to `goto-char' and
  462. the cursor is moved to that point.
  463.  
  464. 
  465. File: emacs-lisp-intro.info,  Node: beginning-of-buffer complete,  Prev: beginning-of-buffer opt arg,  Up: beginning-of-buffer
  466.  
  467. The Complete `beginning-of-buffer'
  468. ----------------------------------
  469.  
  470.    Here is the complete text of the `beginning-of-buffer' function:
  471.  
  472.      (defun beginning-of-buffer (&optional arg)
  473.        "Move point to the beginning of the buffer;
  474.      leave mark at previous position.
  475.      With arg N, put point N/10 of the way
  476.      from the true beginning.
  477.      Don't use this in Lisp programs!
  478.      \(goto-char (point-min)) is faster
  479.      and does not set the mark."
  480.        (interactive "P")
  481.        (push-mark)
  482.        (goto-char
  483.         (if arg
  484.             (if (> (buffer-size) 10000)
  485.                 ;; Avoid overflow for large buffer sizes!
  486.                 (* (prefix-numeric-value arg)
  487.                    (/ (buffer-size) 10))
  488.               (/ (+ 10 (* (buffer-size)
  489.                           (prefix-numeric-value arg)))
  490.                  10))
  491.           (point-min)))
  492.        (if arg (forward-line 1)))
  493.  
  494. Except for two small points, the previous discussion shows how this
  495. function works.  The first point deals with a detail in the
  496. documentation string, and the second point concerns the last line of
  497. the function.
  498.  
  499.    In the documentation string, there is reference to an expression:
  500.  
  501.      \(goto-char (point-min))
  502.  
  503. A `\' is used before the first parenthesis of this expression.  This
  504. `\' tells the Lisp interpreter that the expression should be printed as
  505. shown in the documentation rather than evaluated as a symbolic
  506. expression, which is what it looks like.
  507.  
  508.    Finally, the last line of the `beginning-of-buffer' command says to
  509. move point to the beginning of the next line if the command is invoked
  510. with an argument:
  511.  
  512.      (if arg (forward-line 1)))
  513.  
  514. This puts the cursor at the beginning of the first line after the
  515. appropriate tenths position in the buffer.  This is a flourish that
  516. means that the cursor is always located _at least_ the requested tenths
  517. of the way through the buffer, which is a nicety that is, perhaps, not
  518. necessary, but which, if it did not occur, would be sure to draw
  519. complaints.
  520.  
  521. 
  522. File: emacs-lisp-intro.info,  Node: Second Buffer Related Review,  Next: optional Exercise,  Prev: beginning-of-buffer,  Up: More Complex
  523.  
  524. Review
  525. ======
  526.  
  527.    Here is a brief summary of some of the topics covered in this
  528. chapter.
  529.  
  530. `or'
  531.      Evaluate each argument in sequence, and return the value of the
  532.      first argument that is not `nil'; if none return a value that is
  533.      not `nil', return `nil'.  In brief, return the first true value of
  534.      the arguments; return a true value if one _or_ any of the other
  535.      are true.
  536.  
  537. `and'
  538.      Evaluate each argument in sequence, and if any are `nil', return
  539.      `nil'; if none are `nil', return the value of the last argument.
  540.      In brief, return a true value only if all the arguments are true;
  541.      return a true value if one _and_ each of the others is true.
  542.  
  543. `&optional'
  544.      A keyword used to indicate that an argument to a function
  545.      definition is optional; this means that the function can be
  546.      evaluated without the argument, if desired.
  547.  
  548. `prefix-numeric-value'
  549.      Convert the `raw prefix argument' produced by `(interactive "P")'
  550.      to a numeric value.
  551.  
  552. `forward-line'
  553.      Move point forward to the beginning of the next line, or if the
  554.      argument is greater than one, forward that many lines.  If it
  555.      can't move as far forward as it is supposed to, `forward-line'
  556.      goes forward as far as it can and then returns a count of the
  557.      number of additional lines it was supposed to move but couldn't.
  558.  
  559. `erase-buffer'
  560.      Delete the entire contents of the current buffer.
  561.  
  562. `bufferp'
  563.      Return `t' if its argument is a buffer; otherwise return `nil'.
  564.  
  565. 
  566. File: emacs-lisp-intro.info,  Node: optional Exercise,  Prev: Second Buffer Related Review,  Up: More Complex
  567.  
  568. `optional' Argument Exercise
  569. ============================
  570.  
  571.    Write an interactive function with an optional argument that tests
  572. whether its argument, a number, is greater or less than the value of
  573. `fill-column', and tells you which, in a message.  However, if you do
  574. not pass an argument to the function, use 56 as a default value.
  575.  
  576. 
  577. File: emacs-lisp-intro.info,  Node: Narrowing & Widening,  Next: car cdr & cons,  Prev: More Complex,  Up: Top
  578.  
  579. Narrowing and Widening
  580. **********************
  581.  
  582.    Narrowing is a feature of Emacs that makes it possible for you to
  583. focus on a specific part of a buffer, and work without accidentally
  584. changing other parts.  Narrowing is normally disabled since it can
  585. confuse novices.
  586.  
  587. * Menu:
  588.  
  589. * Narrowing advantages::        The advantages of narrowing
  590. * save-restriction::            The `save-restriction' special form.
  591. * what-line::                   The number of the line that point is on.
  592. * narrow Exercise::
  593.  
  594. 
  595. File: emacs-lisp-intro.info,  Node: Narrowing advantages,  Next: save-restriction,  Prev: Narrowing & Widening,  Up: Narrowing & Widening
  596.  
  597. The Advantages of Narrowing
  598. ===========================
  599.  
  600.    With narrowing, the rest of a buffer is made invisible, as if it
  601. weren't there.  This is an advantage if, for example, you want to
  602. replace a word in one part of a buffer but not in another: you narrow
  603. to the part you want and the replacement is carried out only in that
  604. section, not in the rest of the buffer.  Searches will only work within
  605. a narrowed region, not outside of one, so if you are fixing a part of a
  606. document, you can keep yourself from accidentally finding parts you do
  607. not need to fix by narrowing just to the region you want.  (The key
  608. binding for `narrow-to-region' is `C-x n n'.)
  609.  
  610.    However, narrowing does make the rest of the buffer invisible, which
  611. can scare people who inadvertently invoke narrowing and think they have
  612. deleted a part of their file.  Moreover, the `undo' command (which is
  613. usually bound to `C-x u') does not turn off narrowing (nor should it),
  614. so people can become quite desperate if they do not know that they can
  615. return the rest of a buffer to visibility with the `widen' command.
  616. (The key binding for `widen' is `C-x n w'.)
  617.  
  618.    Narrowing is just as useful to the Lisp interpreter as to a human.
  619. Often, an Emacs Lisp function is designed to work on just part of a
  620. buffer; or conversely, an Emacs Lisp function needs to work on all of a
  621. buffer that has been narrowed.  The `what-line' function, for example,
  622. removes the narrowing from a buffer, if it has any narrowing and when
  623. it has finished its job, restores the narrowing to what it was.  On the
  624. other hand, the `count-lines' function, which is called by `what-line',
  625. uses narrowing to restrict itself to just that portion of the buffer in
  626. which it is interested and then restores the previous situation.
  627.  
  628. 
  629. File: emacs-lisp-intro.info,  Node: save-restriction,  Next: what-line,  Prev: Narrowing advantages,  Up: Narrowing & Widening
  630.  
  631. The `save-restriction' Special Form
  632. ===================================
  633.  
  634.    In Emacs Lisp, you can use the `save-restriction' special form to
  635. keep track of whatever narrowing is in effect, if any.  When the Lisp
  636. interpreter meets with `save-restriction', it executes the code in the
  637. body of the `save-restriction' expression, and then undoes any changes
  638. to narrowing that the code caused.  If, for example, the buffer is
  639. narrowed and the code that follows `save-restriction' gets rid of the
  640. narrowing, `save-restriction' returns the buffer to its narrowed region
  641. afterwards.  In the `what-line' command, any narrowing the buffer may
  642. have is undone by the `widen' command that immediately follows the
  643. `save-restriction' command.  Any original narrowing is restored just
  644. before the completion of the function.
  645.  
  646.    The template for a `save-restriction' expression is simple:
  647.  
  648.      (save-restriction
  649.        BODY... )
  650.  
  651. The body of the `save-restriction' is one or more expressions that will
  652. be evaluated in sequence by the Lisp interpreter.
  653.  
  654.    Finally, a point to note: when you use both `save-excursion' and
  655. `save-restriction', one right after the other, you should use
  656. `save-excursion' outermost.  If you write them in reverse order, you
  657. may fail to record narrowing in the buffer to which Emacs switches
  658. after calling `save-excursion'.  Thus, when written together,
  659. `save-excursion' and `save-restriction' should be written like this:
  660.  
  661.      (save-excursion
  662.        (save-restriction
  663.          BODY...))
  664.  
  665.    In other circumstances, when not written together, the
  666. `save-excursion' and `save-restriction' special forms must be written
  667. in the order appropriate to the function.
  668.  
  669.    For example,
  670.  
  671.        (save-restriction
  672.          (widen)
  673.          (save-excursion
  674.          BODY...))
  675.  
  676. 
  677. File: emacs-lisp-intro.info,  Node: what-line,  Next: narrow Exercise,  Prev: save-restriction,  Up: Narrowing & Widening
  678.  
  679. `what-line'
  680. ===========
  681.  
  682.    The `what-line' command tells you the number of the line in which
  683. the cursor is located.  The function illustrates the use of the
  684. `save-restriction' and `save-excursion' commands.  Here is the text of
  685. the function in full:
  686.  
  687.      (defun what-line ()
  688.        "Print the current line number (in the buffer) of point."
  689.        (interactive)
  690.        (save-restriction
  691.          (widen)
  692.          (save-excursion
  693.            (beginning-of-line)
  694.            (message "Line %d"
  695.                     (1+ (count-lines 1 (point)))))))
  696.  
  697.    The function has a documentation line and is interactive, as you
  698. would expect.  The next two lines use the functions `save-restriction'
  699. and `widen'.
  700.  
  701.    The `save-restriction' special form notes whatever narrowing is in
  702. effect, if any, in the current buffer and restores that narrowing after
  703. the code in the body of the `save-restriction' has been evaluated.
  704.  
  705.    The `save-restriction' special form is followed by `widen'.  This
  706. function undoes any narrowing the current buffer may have had when
  707. `what-line' was called.  (The narrowing that was there is the narrowing
  708. that `save-restriction' remembers.)  This widening makes it possible
  709. for the line counting commands to count from the beginning of the
  710. buffer.  Otherwise, they would have been limited to counting within the
  711. accessible region.  Any original narrowing is restored just before the
  712. completion of the function by the `save-restriction' special form.
  713.  
  714.    The call to `widen' is followed by `save-excursion', which saves the
  715. location of the cursor (i.e., of point) and of the mark, and restores
  716. them after the code in the body of the `save-excursion' uses the
  717. `beginning-of-line' function to move point.
  718.  
  719.    (Note that the `(widen)' expression comes between the
  720. `save-restriction' and `save-excursion' special forms.  When you write
  721. the two `save- ...' expressions in sequence, write `save-excursion'
  722. outermost.)
  723.  
  724.    The last two lines of the `what-line' function are functions to
  725. count the number of lines in the buffer and then print the number in the
  726. echo area.
  727.  
  728.      (message "Line %d"
  729.               (1+ (count-lines 1 (point)))))))
  730.  
  731.    The `message' function prints a one-line message at the bottom of the
  732. Emacs screen.  The first argument is inside of quotation marks and is
  733. printed as a string of characters.  However, it may contain `%d', `%s',
  734. or `%c' to print arguments that follow the string.  `%d' prints the
  735. argument as a decimal, so the message will say something such as `Line
  736. 243'.
  737.  
  738.    The number that is printed in place of the `%d' is computed by the
  739. last line of the function:
  740.  
  741.      (1+ (count-lines 1 (point)))
  742.  
  743. What this does is count the lines from the first position of the
  744. buffer, indicated by the `1', up to `(point)', and then add one to that
  745. number.  (The `1+' function adds one to its argument.)  We add one to
  746. it because line 2 has only one line before it, and `count-lines' counts
  747. only the lines _before_ the current line.
  748.  
  749.    After `count-lines' has done its job, and the message has been
  750. printed in the echo area, the `save-excursion' restores point and mark
  751. to their original positions; and `save-restriction' restores the
  752. original narrowing, if any.
  753.  
  754. 
  755. File: emacs-lisp-intro.info,  Node: narrow Exercise,  Prev: what-line,  Up: Narrowing & Widening
  756.  
  757. Exercise with Narrowing
  758. =======================
  759.  
  760.    Write a function that will display the first 60 characters of the
  761. current buffer, even if you have narrowed the buffer to its latter half
  762. so that the first line is inaccessible.  Restore point, mark, and
  763. narrowing.  For this exercise, you need to use `save-restriction',
  764. `widen', `goto-char', `point-min', `buffer-substring', `message', and
  765. other functions, a whole potpourri.
  766.  
  767. 
  768. File: emacs-lisp-intro.info,  Node: car cdr & cons,  Next: Cutting & Storing Text,  Prev: Narrowing & Widening,  Up: Top
  769.  
  770. `car', `cdr', `cons': Fundamental Functions
  771. *******************************************
  772.  
  773.    In Lisp, `car', `cdr', and `cons' are fundamental functions.  The
  774. `cons' function is used to construct lists, and the `car' and `cdr'
  775. functions are used to take them apart.
  776.  
  777.    In the walk through of the `copy-region-as-kill' function, we will
  778. see `cons' as well as two variants on `cdr', namely, `setcdr' and
  779. `nthcdr'.  (*Note copy-region-as-kill::.)
  780.  
  781. * Menu:
  782.  
  783. * Strange Names::               An historical aside: why the strange names?
  784. * car & cdr::                   Functions for extracting part of a list.
  785. * cons::                        Constructing a list.
  786. * nthcdr::                      Calling `cdr' repeatedly.
  787. * nth::
  788. * setcar::                      Changing the first element of a list.
  789. * setcdr::                      Changing the rest of a list.
  790. * cons Exercise::
  791.  
  792. 
  793. File: emacs-lisp-intro.info,  Node: Strange Names,  Next: car & cdr,  Prev: car cdr & cons,  Up: car cdr & cons
  794.  
  795. Strange Names
  796. =============
  797.  
  798.    The name of the `cons' function is not unreasonable: it is an
  799. abbreviation of the word `construct'.  The origins of the names for
  800. `car' and `cdr', on the other hand, are esoteric: `car' is an acronym
  801. from the phrase `Contents of the Address part of the Register'; and
  802. `cdr' (pronounced `could-er') is an acronym from the phrase `Contents
  803. of the Decrement part of the Register'.  These phrases refer to
  804. specific pieces of hardware on the very early computer on which the
  805. original Lisp was developed.  Besides being obsolete, the phrases have
  806. been completely irrelevant for more than 25 years to anyone thinking
  807. about Lisp.  Nonetheless, although a few brave scholars have begun to
  808. use more reasonable names for these functions, the old terms are still
  809. in use.  In particular, since the terms are used in the Emacs Lisp
  810. source code, we will use them in this introduction.
  811.  
  812. 
  813. File: emacs-lisp-intro.info,  Node: car & cdr,  Next: cons,  Prev: Strange Names,  Up: car cdr & cons
  814.  
  815. `car' and `cdr'
  816. ===============
  817.  
  818.    The CAR of a list is, quite simply, the first item in the list.
  819. Thus the CAR of the list `(rose violet daisy buttercup)' is `rose'.
  820.  
  821.    If you are reading this in Info in GNU Emacs, you can see this by
  822. evaluating the following:
  823.  
  824.      (car '(rose violet daisy buttercup))
  825.  
  826. After evaluating the expression, `rose' will appear in the echo area.
  827.  
  828.    Clearly, a more reasonable name for the `car' function would be
  829. `first' and this is often suggested.
  830.  
  831.    `car' does not remove the first item from the list; it only reports
  832. what it is.  After `car' has been applied to a list, the list is still
  833. the same as it was.  In the jargon, `car' is `non-destructive'.  This
  834. feature turns out to be important.
  835.  
  836.    The CDR of a list is the rest of the list, that is, the `cdr'
  837. function returns the part of the list that follows the first item.
  838. Thus, while the CAR of the list `'(rose violet daisy buttercup)' is
  839. `rose', the rest of the list, the value returned by the `cdr' function,
  840. is `(violet daisy buttercup)'.
  841.  
  842.    You can see this by evaluating the following in the usual way:
  843.  
  844.      (cdr '(rose violet daisy buttercup))
  845.  
  846. When you evaluate this, `(violet daisy buttercup)' will appear in the
  847. echo area.
  848.  
  849.    Like `car', `cdr' does not remove any elements from the list--it
  850. just returns a report of what the second and subsequent elements are.
  851.  
  852.    Incidentally, in the example, the list of flowers is quoted.  If it
  853. were not, the Lisp interpreter would try to evaluate the list by calling
  854. `rose' as a function.  In this example, we do not want to do that.
  855.  
  856.    Clearly, a more reasonable name for `cdr' would be `rest'.
  857.  
  858.    (There is a lesson here: when you name new functions, consider very
  859. carefully what you are doing, since you may be stuck with the names for
  860. far longer than you expect.  The reason this document perpetuates these
  861. names is that the Emacs Lisp source code uses them, and if I did not
  862. use them, you would have a hard time reading the code; but do, please,
  863. try to avoid using these terms yourself.  The people who come after you
  864. will be grateful to you.)
  865.  
  866.    When `car' and `cdr' are applied to a list made up of symbols, such
  867. as the list `(pine fir oak maple)', the element of the list returned by
  868. the function `car' is the symbol `pine' without any parentheses around
  869. it.  `pine' is the first element in the list.  However, the CDR of the
  870. list is a list itself, `(fir oak maple)', as you can see by evaluating
  871. the following expressions in the usual way:
  872.  
  873.      (car '(pine fir oak maple))
  874.      
  875.      (cdr '(pine fir oak maple))
  876.  
  877.    On the other hand, in a list of lists, the first element is itself a
  878. list.  `car' returns this first element as a list.  For example, the
  879. following list contains three sub-lists, a list of carnivores, a list
  880. of herbivores and a list of sea mammals:
  881.  
  882.      (car '((lion tiger cheetah)
  883.             (gazelle antelope zebra)
  884.             (whale dolphin seal)))
  885.  
  886. In this example, the first element or CAR of the list is the list of
  887. carnivores, `(lion tiger cheetah)', and the rest of the list is
  888. `((gazelle antelope zebra) (whale dolphin seal))'.
  889.  
  890.      (cdr '((lion tiger cheetah)
  891.             (gazelle antelope zebra)
  892.             (whale dolphin seal)))
  893.  
  894.    It is worth saying again that `car' and `cdr' are
  895. non-destructive--that is, they do not modify or change lists to which
  896. they are applied.  This is very important for how they are used.
  897.  
  898.    Also, in the first chapter, in the discussion about atoms, I said
  899. that in Lisp, "certain kinds of atom, such as an array, can be separated
  900. into parts; but the mechanism for doing this is different from the
  901. mechanism for splitting a list.  As far as Lisp is concerned, the atoms
  902. of a list are unsplittable."  (*Note Lisp Atoms::.)  The `car' and
  903. `cdr' functions are used for splitting lists and are considered
  904. fundamental to Lisp.  Since they cannot split or gain access to the
  905. parts of an array, an array is considered an atom.  Conversely, the
  906. other fundamental function, `cons', can put together or construct a
  907. list, but not an array.  (Arrays are handled by array-specific
  908. functions.  *Note Arrays: (elisp)Arrays.)
  909.  
  910. 
  911. File: emacs-lisp-intro.info,  Node: cons,  Next: nthcdr,  Prev: car & cdr,  Up: car cdr & cons
  912.  
  913. `cons'
  914. ======
  915.  
  916.    The `cons' function constructs lists; it is the inverse of `car' and
  917. `cdr'.  For example, `cons' can be used to make a four element list
  918. from the three element list, `(fir oak maple)':
  919.  
  920.      (cons 'pine '(fir oak maple))
  921.  
  922. After evaluating this list, you will see
  923.  
  924.      (pine fir oak maple)
  925.  
  926. appear in the echo area.  `cons' puts a new element at the beginning of
  927. a list; it attaches or pushes elements onto the list.
  928.  
  929. * Menu:
  930.  
  931. * Build a list::
  932. * length::                      How to find the length of a list.
  933.  
  934. 
  935. File: emacs-lisp-intro.info,  Node: Build a list,  Next: length,  Prev: cons,  Up: cons
  936.  
  937. Build a list
  938. ------------
  939.  
  940.    `cons' must have a list to attach to.(1)  You cannot start from
  941. absolutely nothing.  If you are building a list, you need to provide at
  942. least an empty list at the beginning.  Here is a series of `cons'
  943. expressions that build up a list of flowers.  If you are reading this
  944. in Info in GNU Emacs, you can evaluate each of the expressions in the
  945. usual way; the value is printed in this text after `=>', which you may
  946. read as `evaluates to'.
  947.  
  948.      (cons 'buttercup ())
  949.           => (buttercup)
  950.      
  951.      (cons 'daisy '(buttercup))
  952.           => (daisy buttercup)
  953.      
  954.      (cons 'violet '(daisy buttercup))
  955.           => (violet daisy buttercup)
  956.      
  957.      (cons 'rose '(violet daisy buttercup))
  958.           => (rose violet daisy buttercup)
  959.  
  960. In the first example, the empty list is shown as `()' and a list made
  961. up of `buttercup' followed by the empty list is constructed.  As you
  962. can see, the empty list is not shown in the list that was constructed.
  963. All that you see is `(buttercup)'.  The empty list is not counted as an
  964. element of a list because there is nothing in an empty list.  Generally
  965. speaking, an empty list is invisible.
  966.  
  967.    The second example, `(cons 'daisy '(buttercup))' constructs a new,
  968. two element list by putting `daisy' in front of `buttercup'; and the
  969. third example constructs a three element list by putting `violet' in
  970. front of `daisy' and `buttercup'.
  971.  
  972.    ---------- Footnotes ----------
  973.  
  974.    (1) Actually, you can `cons' an element to an atom to produce a
  975. dotted pair.  Dotted pairs are not discussed here; see *Note Dotted
  976. Pair Notation: (elisp)Dotted Pair Notation.
  977.  
  978. 
  979. File: emacs-lisp-intro.info,  Node: length,  Prev: Build a list,  Up: cons
  980.  
  981. Find the Length of a List: `length'
  982. -----------------------------------
  983.  
  984.    You can find out how many elements there are in a list by using the
  985. Lisp function `length', as in the following examples:
  986.  
  987.      (length '(buttercup))
  988.           => 1
  989.      
  990.      (length '(daisy buttercup))
  991.           => 2
  992.      
  993.      (length (cons 'violet '(daisy buttercup)))
  994.           => 3
  995.  
  996. In the third example, the `cons' function is used to construct a three
  997. element list which is then passed to the `length' function as its
  998. argument.
  999.  
  1000.    We can also use `length' to count the number of elements in an empty
  1001. list:
  1002.  
  1003.      (length ())
  1004.           => 0
  1005.  
  1006. As you would expect, the number of elements in an empty list is zero.
  1007.  
  1008.    An interesting experiment is to find out what happens if you try to
  1009. find the length of no list at all; that is, if you try to call `length'
  1010. without giving it an argument, not even an empty list:
  1011.  
  1012.      (length )
  1013.  
  1014. What you see, if you evaluate this, is the error message
  1015.  
  1016.      Wrong number of arguments: #<subr length>, 0
  1017.  
  1018. This means that the function receives the wrong number of arguments,
  1019. zero, when it expects some other number of arguments.  In this case,
  1020. one argument is expected, the argument being a list whose length the
  1021. function is measuring.  (Note that _one_ list is _one_ argument, even
  1022. if the list has many elements inside it.)
  1023.  
  1024.    The part of the error message that says `#<subr length>' is the name
  1025. of the function.  This is written with a special notation, `#<subr',
  1026. that indicates that the function `length' is one of the primitive
  1027. functions written in C rather than in Emacs Lisp.  (`subr' is an
  1028. abbreviation for `subroutine'.)  *Note What Is a Function?: (elisp)What
  1029. Is a Function, for more about subroutines.
  1030.  
  1031. 
  1032. File: emacs-lisp-intro.info,  Node: nthcdr,  Next: nth,  Prev: cons,  Up: car cdr & cons
  1033.  
  1034. `nthcdr'
  1035. ========
  1036.  
  1037.    The `nthcdr' function is associated with the `cdr' function.  What
  1038. it does is take the CDR of a list repeatedly.
  1039.  
  1040.    If you take the CDR of the list `(pine fir oak maple)', you will be
  1041. returned the list `(fir oak maple)'.  If you repeat this on what was
  1042. returned, you will be returned the list `(oak maple)'.  (Of course,
  1043. repeated CDRing on the original list will just give you the original
  1044. CDR since the function does not change the list.  You need to evaluate
  1045. the CDR of the CDR and so on.)  If you continue this, eventually you
  1046. will be returned an empty list, which in this case, instead of being
  1047. shown as `()' is shown as `nil'.
  1048.  
  1049.    For review, here is a series of repeated CDRs, the text following
  1050. the `=>' shows what is returned.
  1051.  
  1052.      (cdr '(pine fir oak maple))
  1053.           =>(fir oak maple)
  1054.      
  1055.      (cdr '(fir oak maple))
  1056.           => (oak maple)
  1057.      
  1058.      (cdr '(oak maple))
  1059.           =>(maple)
  1060.      
  1061.      (cdr '(maple))
  1062.           => nil
  1063.      
  1064.      (cdr 'nil)
  1065.           => nil
  1066.      
  1067.      (cdr ())
  1068.           => nil
  1069.  
  1070.    You can also do several CDRs without printing the values in between,
  1071. like this:
  1072.  
  1073.      (cdr (cdr '(pine fir oak maple)))
  1074.           => (oak maple)
  1075.  
  1076. In this example, the Lisp interpreter evaluates the innermost list
  1077. first.  The innermost list is quoted, so it just passes the list as it
  1078. is to the innermost `cdr'.  This `cdr' passes a list made up of the
  1079. second and subsequent elements of the list to the outermost `cdr',
  1080. which produces a list composed of the third and subsequent elements of
  1081. the original list.  In this example, the `cdr' function is repeated and
  1082. returns a list that consists of the original list without its first two
  1083. elements.
  1084.  
  1085.    The `nthcdr' function does the same as repeating the call to `cdr'.
  1086. In the following example, the argument 2 is passed to the function
  1087. `nthcdr', along with the list, and the value returned is the list
  1088. without its first two items, which is exactly the same as repeating
  1089. `cdr' twice on the list:
  1090.  
  1091.      (nthcdr 2 '(pine fir oak maple))
  1092.           => (oak maple)
  1093.  
  1094.    Using the original four element list, we can see what happens when
  1095. various numeric arguments are passed to `nthcdr', including 0, 1, and 5:
  1096.  
  1097.      ;; Leave the list as it was.
  1098.      (nthcdr 0 '(pine fir oak maple))
  1099.           => (pine fir oak maple)
  1100.      
  1101.      ;; Return a copy without the first element.
  1102.      (nthcdr 1 '(pine fir oak maple))
  1103.           => (fir oak maple)
  1104.      
  1105.      ;; Return a copy of the list without three elements.
  1106.      (nthcdr 3 '(pine fir oak maple))
  1107.           => (maple)
  1108.      
  1109.      ;; Return a copy lacking all four elements.
  1110.      (nthcdr 4 '(pine fir oak maple))
  1111.           => nil
  1112.      
  1113.      ;; Return a copy lacking all elements.
  1114.      (nthcdr 5 '(pine fir oak maple))
  1115.           => nil
  1116.  
  1117. 
  1118. File: emacs-lisp-intro.info,  Node: nth,  Next: setcar,  Prev: nthcdr,  Up: car cdr & cons
  1119.  
  1120. `nth'
  1121. =====
  1122.  
  1123.    The `nthcdr' function takes the CDR of a list repeatedly.  The `nth'
  1124. function takes the CAR of the result returned by `nthcdr'.  It returns
  1125. the Nth element of the list.
  1126.  
  1127.    Thus, if it were not defined in C for speed, the definition of `nth'
  1128. would be:
  1129.  
  1130.      (defun nth (n list)
  1131.        "Returns the Nth element of LIST.
  1132.      N counts from zero.  If LIST is not that long, nil is returned."
  1133.        (car (nthcdr n list)))
  1134.  
  1135. (Originally, `nth' was defined in Emacs Lisp in `subr.el', but its
  1136. definition was redone in C in the 1980s.)
  1137.  
  1138.    The `nth' function returns a single element of a list.  This can be
  1139. very convenient.
  1140.  
  1141.    Note that the elements are numbered from zero, not one.  That is to
  1142. say, the first element of a list, its CAR is the zeroth element.  This
  1143. is called `zero-based' counting and often bothers people who are
  1144. accustomed to the first element in a list being number one, which is
  1145. `one-based'.
  1146.  
  1147.    For example:
  1148.  
  1149.      (nth 0 '("one" "two" "three"))
  1150.          => "one"
  1151.      
  1152.      (nth 1 '("one" "two" "three"))
  1153.          => "two"
  1154.  
  1155.    It is worth mentioning that `nth', like `nthcdr' and `cdr', does not
  1156. change the original list--the function is non-destructive.  This is in
  1157. sharp contrast to the `setcar' and `setcdr' functions.
  1158.  
  1159. 
  1160. File: emacs-lisp-intro.info,  Node: setcar,  Next: setcdr,  Prev: nth,  Up: car cdr & cons
  1161.  
  1162. `setcar'
  1163. ========
  1164.  
  1165.    As you might guess from their names, the `setcar' and `setcdr'
  1166. functions set the CAR or the CDR of a list to a new value.  They
  1167. actually change the original list, unlike `car' and `cdr' which leave
  1168. the original list as it was.  One way to find out how this works is to
  1169. experiment.  We will start with the `setcar' function.
  1170.  
  1171.    First, we can make a list and then set the value of a variable to the
  1172. list, using the `setq' function.  Here is a list of animals:
  1173.  
  1174.      (setq animals '(antelope giraffe lion tiger))
  1175.  
  1176. If you are reading this in Info inside of GNU Emacs, you can evaluate
  1177. this expression in the usual fashion, by positioning the cursor after
  1178. the expression and typing `C-x C-e'.  (I'm doing this right here as I
  1179. write this.  This is one of the advantages of having the interpreter
  1180. built into the computing environment.)
  1181.  
  1182.    When we evaluate the variable `animals', we see that it is bound to
  1183. the list `(antelope giraffe lion tiger)':
  1184.  
  1185.      animals
  1186.           => (antelope giraffe lion tiger)
  1187.  
  1188. Put another way, the variable `animals' points to the list `(antelope
  1189. giraffe lion tiger)'.
  1190.  
  1191.    Next, evaluate the function `setcar' while passing it two arguments,
  1192. the variable `animals' and the quoted symbol `hippopotamus'; this is
  1193. done by writing the three element list `(setcar animals 'hippopotamus)'
  1194. and then evaluating it in the usual fashion:
  1195.  
  1196.      (setcar animals 'hippopotamus)
  1197.  
  1198. After evaluating this expression, evaluate the variable `animals'
  1199. again.  You will see that the list of animals has changed:
  1200.  
  1201.      animals
  1202.           => (hippopotamus giraffe lion tiger)
  1203.  
  1204. The first element on the list, `antelope' is replaced by `hippopotamus'.
  1205.  
  1206.    So we can see that `setcar' did not add a new element to the list as
  1207. `cons' would have; it replaced `giraffe' with `hippopotamus'; it
  1208. _changed_ the list.
  1209.  
  1210. 
  1211. File: emacs-lisp-intro.info,  Node: setcdr,  Next: cons Exercise,  Prev: setcar,  Up: car cdr & cons
  1212.  
  1213. `setcdr'
  1214. ========
  1215.  
  1216.    The `setcdr' function is similar to the `setcar' function, except
  1217. that the function replaces the second and subsequent elements of a list
  1218. rather than the first element.
  1219.  
  1220.    To see how this works, set the value of the variable to a list of
  1221. domesticated animals by evaluating the following expression:
  1222.  
  1223.      (setq domesticated-animals '(horse cow sheep goat))
  1224.  
  1225. If you now evaluate the list, you will be returned the list `(horse cow
  1226. sheep goat)':
  1227.  
  1228.      domesticated-animals
  1229.           => (horse cow sheep goat)
  1230.  
  1231.    Next, evaluate `setcdr' with two arguments, the name of the variable
  1232. which has a list as its value, and the list to which the CDR of the
  1233. first list will be set;
  1234.  
  1235.      (setcdr domesticated-animals '(cat dog))
  1236.  
  1237. If you evaluate this expression, the list `(cat dog)' will appear in
  1238. the echo area.  This is the value returned by the function.  The result
  1239. we are interested in is the "side effect", which we can see by
  1240. evaluating the variable `domesticated-animals':
  1241.  
  1242.      domesticated-animals
  1243.           => (horse cat dog)
  1244.  
  1245. Indeed, the list is changed from `(horse cow sheep goat)' to `(horse
  1246. cat dog)'.  The CDR of the list is changed from `(cow sheep goat)' to
  1247. `(cat dog)'.
  1248.  
  1249. 
  1250. File: emacs-lisp-intro.info,  Node: cons Exercise,  Prev: setcdr,  Up: car cdr & cons
  1251.  
  1252. Exercise
  1253. ========
  1254.  
  1255.    Construct a list of four birds by evaluating several expressions with
  1256. `cons'.  Find out what happens when you `cons' a list onto itself.
  1257. Replace the first element of the list of four birds with a fish.
  1258. Replace the rest of that list with a list of other fish.
  1259.  
  1260.